perm filename MONITR.WRU[SYS,HE]1 blob
sn#004176 filedate 1972-06-01 generic text, type T, neo UTF8
00100 %TOP,,HAND-EYE SYSTEM PART III , ,1-1
00150
00200
00300
00400
00500
00600
00700
00800
00900
01000
01100
01200
01300
01400
01500
01600 SYSTEM MANUAL FOR HAND-EYE HACKERS
01700
01720 PART I. [HAND.WRU]
01740 PART II. MESSAGE PROCEDURES [MESSAG.WRU]
01800 PART III. MONITOR [MONITR.WRU]
01820 SECTION 1. TELETYPE CONTROLLER
01840 SECTION 2. STRING DESTINATIONS
01860 SECTION 3. SENDING SYSTEM COMMANDS
01880 SECTION 4. MONITOR COMMANDS
01900 SECTION 5. OUTPUT
01920 SECTION 6. RUN NUMBER
01940 SECTION 7. TRACE OUTPUT
01960 SECTION 8. ERROR MESSAGES
00100 1.0 TELETYPE CONTROLLER
00200
00300 You the USER (note the capitalization -- we dare not lose the user
00400 among the 300000 words of code flying around) shall sit at a display
00500 and shall control the system with great patience and perseverence.
00600
00700 The TTY controller is responsible for several modes of communication
00800 between you and your modules. All this communication is effected by
00900 pseudo-teletypes:
01000
01100
01200 user TTY ------------------------→ module PTY
01300 systems commands
01400 regular input to module
01500 .....
01600
01700
01800 user display ←----------------------- module PTY
01900 any module output
02000 system error messages
02100 .....
02200
02300
02400 There are two modes of character passing, line mode and character
02500 mode (line is assumed at start). In line mode, a whole line
02600 (terminated by <cr> or other activation character) is assembled
02700 before it is passed along one of the routes drawn. In character
02800 mode, individual characters are passed. You may ask: why the
02900 distinction? There are several reasons:
03000
03100 1. Line mode allows you to edit your typein at the display. Then the
03200 <cr> dispatches the (possibly edited) line. If you are in character
03300 mode, the program eats characters as fast (?) as you type them, thus
03400 not allowing you to edit. In line mode, a module must type a full
03500 line (terminated by <cr>) before the output will appear on your
03600 screen. If this is inconvenient, use character mode (to be avoided
03700 due to inefficiency). NOTE: character mode is currently disabled for
03800 TTY input. Subjobs may still output in character mode.
03900
04000 2. If output from several modules is appearing on your display
04100 "simultaneously", there may be a problem with readibility. In line
04200 mode, output is interspersed on a line-by-line basis. In character
04300 mode, output is interspersed on a character-by- character basis
04400 (could be a mumbo jumbo!).
04500
04600 There are two modes of typing at your modules, and one mode for
04700 typing commands to the TTY controller itself.
04800
00100 2.0 Pushing strings at your modules
00200
00300
00400 There are some formats of strings which are intercepted by the TTY
00500 controller for its own information (e.g. routing). Each module has a
00600 logical name for the purposes of the TTY controller which was
00700 assigned when you logged in the job.
00800
00900 log; This is a string for subjob "log" <cr>
01000
01100 This is a line to be passed to the subjob with logical name log.
01200 This routing information is ascertained from the first five
01300 characters of the line: a ";" follows the logical name of the
01400 destination. If no logical name is given, the one most recently used
01500 on input is assumed. This has the nice effect that once you start
01600 talking to a given subjob, you merely type along:
01700
01800 log; This is the first line for "log" <cr>
01900 This is the second line, and "log" is assumed <cr>
02000
02100 The monitor has the logical name "MON". Strings typed with
02200 this destination will be echoed. If tracing is on, they will also be
02300 traced, enabling the user to insert comments into the trace file.
00100 3.0 Sending system commands to your modules.
00200
00300
00400 Commands may be issued to your modules in two ways: (1) using the
00500 string-pushing mechanism described above, and (2) using the command
00600 format, to be described. The difference is: the command format method
00700 issues a ↑C to your module before issuing the command, thus making
00800 sure the PTY is in monitor mode.
00900
01000 The general command format is
01100
01200 log:command
01300
01400 where the ":" is the character which flags this line as a command. If
01500 log is missing, the last logical name cited in a command line will be
01600 assumed. Again, only the first five characters of the string are
01700 examined for the logical name and the ":". If the command is:
01800
01900 ::command
02000 then, for some commands, the command is issued to all modules logged
02100 in under the PTY controller. This command does not change the default
02200 logical name for the command line. Some of the commands can be
02300 applied to the monitor, if the logical name given is "MON". Below is
02400 a list of legal commands. The letters following some commands
02500 indicate that thet can be applied to the monitor (M), or to all
02600 subjobs at once with a double colon (A). The A mode affects the
02700 monitor also if M mode is legal. Legal commands are: EXECUTE, TRY,
02800 DEBUG, LOAD, EDIT, COMPILE, CREATE, CREF, DELETE, TYPE, DIRECTORY,
02900 LIST, RENAME, ZERO, SYSTAT, ASSIGN, CONTINUE(A), CCONTINUE(A),
03000 CORE(A), COREX, DAYTIME, DEASSIGN, DEPOSIT, EXAMINE, FINISH(A), GET,
03100 RUN, PJOB(A), PPPN(A), REENTER, SAVE, START(A), TIME(A) or their
03200 ordinary abbreviations. Note that if the command is not listed, you
03300 can do
03400
03500 FOO:HALT
03600 FOO;command
03700
03800 This can be dangerous since the monitor does not update its
03900 tables for any changes in the job's status. Things like W are ok but
04000 you do ATTACH and DETACH at your peril. It is useful for macros,
04100 where you want a command to wait for the completion of the previous
04200 command.
04300
04400 JOB:COMPILE FOO
04500 JOB;R LOADER
04600
04700 A ':' in the second line above would cause the compile to be
04800 halted immediately and the loader run. This way the second command
04900 will stay in the subjob's input buffer until the compile terminates.
05000
05100 The START, RESTART, and RUN commands will turn off III
05200 displays for that job and release the display frames for other users
05300 (if the display routines in DPYSUB.HDR[II,HE] are being used by the
05400 subjobs.
00100 4.0 TTY controller commands.
00200
00300
00400 The TTY controller accepts several commands for afffecting its
00500 operation. These commands have exactly the same format as the module
00600 command format above. The commands are: (with the mode letters
00700 mentioned in the last section)
00800
00900
01000 1. log:LOGIN xxx,xxx
01100 A subjob with logical name log, which must not currently be
01200 logged in, is logged in under project-programmer number
01300 xxx,xxx. If a PPN is not given, it will be logged in with the
01400 same PPN as the monitor. A message is printed out when the
01500 login phase successfully terminates. Passwords are not
01600 allowed. Any III displays generated by the last subjob with
01700 this job number are deleted.
01800
01900 2. log:KILL (A)
02000 The subjob with logical name log is killed, and the PTY is
02100 released. The program types JOB nn KILLED. Information, if
02200 any, about the job in the second segment message procedure
02300 tables is cleared. The subjob's III displays are deleted.
02400
02500 3. log:HALT (A)
02600 The subjob with logical name log is control-seed (?), i.e.
02700 ↑C↑C is sent to the subjob.
02800
02900 4. log:LINE (AM) log:CHAR (AM)
03000 Enter (or leave) line mode for use in all communications with
03100 this subjob. Note that MON:CHAR is currently a no-op.
03200
03300 5. log:SUPPRESS (A) log:UNSUPPRESS (A)
03400 Suppress (or unsuppress) all output from this subjob. It will
03500 simply go "down the tubes" during the time output is
03600 suppressed, but will be traced if tracing is on.
03700
03800 6. log:TRACE (AM) log:UNTRACE (AM)
03900 Trace all strings going to and coming from this subjob.
04000 MON:TRACE turns on TTY tracing, monitor tracing, and message
04100 tracing. Tracing appears on file DSK:TRACnn.DBG where nn is
04200 the run number (see Section 6.0).
04300
04400 7. log:UPDATE (AM)
04500 This executes the message procedure UPDATE in the subjob to
04600 "close" its debugging trace file(s). This should be done
04700 every so often while tracing, so that a record will be around
04800 even if the system (which one?) dies. MON:UPDATE closes the
04900 monitor trace file [currently this command only works for the
05000 monitor].
05100
05200 8. log:RAID <c1><c2>A
05300 If you wish to debug the code in some module, RAID should be
05400 loaded with the code in that module. But RAID makes use of
05500 control characters, and other funny things, and hence we need
05600 special character mode for passing things back and forth.
05700 This also insures the fastest response to input which you
05800 type. You are effectively directly linked to the RAID in the
05900 subjob with logical name log. During this time, no PTY
06000 output from other subjobs will be displayed to you. To get
06100 out of the RAID mode, type <c1><c2>A. The next character you
06200 type will cause exit from RAID mode. Note that this command
06300 does not enter RAID (which you may already be in, and thus
06400 entering again would cause you to lose your accumulator
06500 contents). The command merely sets up this special
06600 character passing mode. The way to get into RAID from
06700 scratch would be to say:
06800
06900 log:HALT
07000 log;DD
07100 :RAID
07200
07300 For convenience, there is an abbreviation of the last three
07400 lines:
07500
07600 8a. log:DD
07700
07800 There is no problem about the RAID display coming to your
07900 display console. All that is happily handled by the
08000 wonderful Poole display service.
08100
08200 9. log:EOF
08300 This command merely sends EOF (control Z) to the subjob.
08400
08500 10. :DEFINE name argchr
08600 This is the command to define a macro for use by the TTY
08700 controller. This will define a macro with name "name". The
08800 body of the macro is then typed in on the lines following the
08900 command. The first blank line (i.e. just <cr>) terminates the
09000 macro definition. The monitor will then type:
09100
09200 name DEFINED
09300
09400 You may call the macro merely by giving the macro name in
09500 command format:
09600
09700 :name
09800
09900 When it is finished, it will type END MACRO. Macros may call
10000 other macros (much like subroutine calls), and execution of
10100 the original macro will resume after the call is completed.
10200 The logical name, if any, is ignored except to set the
10300 default logical name.
10400 If <argchr> is a printing character, the macro is assumed to
10500 have arguments; otherwise, or if <argchr> does not exist, it
10600 does not. When the macro is called, the arguments follow the
10700 name, seperated from it by spaces or tabs, and are delimited
10800 by commas. The arguments are numbered 1, 2, ....n (n<10).
10900 The ith argument will be substituted for the string <argchr>i
11000 in the macro body. If no such string exists, the argument is
11100 ignored. Arguments needed but not provided are assumed to
11200 be the null string. If <argchr> appears in the macro body
11300 followed by anything other than a digit, it is ignored.
11400
11500 For example:
11600
11700 :DEFINE FOO $
11800 THIS $1 A $2ACRO WITH ARGU$2ENTS
11900 IT $1 AN EX$AMPLE
12000
12100 Then FOO IS,M becomes
12200
12300 THIS IS A MACRO WITH ARGUMENTS
12400 IT IS AN EX$AMPLE
12500
12600 and FOO ,M,FXX becomes
12700
12800 THIS A MACRO WITH ARGUMENTS
12900 IT AN EXAMPLE
13000
13100 11. :DISKIN name[prj,prg]
13200 The logical name, if any, is ignored except to set the
13300 default logical name. This directs the TTY controller to take
13400 its input from the disk file name[prj,prg] (the prj and prg
13500 are optional). This is very useful for initializing your
13600 batch of macro definitions. E.g. the file might say:
13700
13800 :DEFINE IRWIN
13900 SOB:LOGIN 1,SOB
14000 SOB:RUN DSK COLECT
14100 SOB;SEGNAM
14200 SOB;GLBSEG
14300 SOB;SYS
14400
14500 :DEFINE GOGO
14600 :IRWIN
14700 SOB;Y
14800
14900 These are two macros. The first logs in a subjob, starts a
15000 program, and responds to the prompts about global segments.
15100 The second calls the first, and then types "Y" at SOB's
15200 program. This command will type
15300
15400 END DISKIN
15500
15600 when it is finished.
15700
15800 12. log:STATUS (A)
15900
16000 One line is typed giving the job's current status as follows:
16100
16200 LOG+JN NAME PROG PPN RUN_STATUS CORE TTIM ITIM
16300
16400 where LOG is the name by which it is known to the monitor,
16500 NAME is its name in the message procedure handler (the one in
16600 your initial PUT_DATA), and JN is its system job number. NAME
16700 is null if the job has not initialized for message procedures.
16800 RUN_STATUS is the job's system status and may be one of the
16900 following (or null):
17000
17100 LOGING job in LOGIN or LOGOUT
17200 NO_RUN job is in monitor mode and cannot be continued.
17300 (error halt or no job has been started)
17400 RUN job is in user mode
17500
17600 PROG is the name of the program the subjob has in core. PPN
17700 is the subjobs project-programmer number. CORE is the number
17800 of 1K blocks of core the subjob has. TTIM is the subjob's run
17801 time since logging in as MIN:SEC.FRACTION. ITIM is the
17802 incremental runtime since STATUS was last executed for this
17803 subjob. The last number is for ANDY. If ::STATUS is given,
18000 the size of the monitor an second segment is determined also
18100 and a line typed giving the total core in use, the upper seg-
18200 ment size, the maximum subjob size the system can currently
18300 handle, and the amount the largest subjob can increase in
18400 size before running out of core.
18500
18600 13. log:SET CHAR (A) log:RESET CHAR (A)
18700
18800 These commands set and reset (clear) the typing (TYP_@) and
18900 debugging (DEB_@) flags in the global model for the specified
19000 job(s). They are noops for jobs not defined in the global
19100 model. The argument specifies the flag. Its first characters
19200 must be DE for the debug flag and T for the type flag. The
19300 display flag (DIS_@) can be changed by specifying DI.
19400
19500 JOB:RESET DISPLAY turns of JOB's III displays but does NOT
19600 release the frames for other users.
19700
19800
19900 14. :RESTART DEV:FILE
20000
20100 This command restarts the monitor and the second segment,
20200 putting them is a state where typing START to all subjobs
20300 will do the right thing. The command starts by typing
20400
20500 DO YOU REALLY WANT TO RESTART??
20600
20700 If you type Y it will executed; otherwise it is ignored. The
20800 default names for input strings are cleared, all DISKIN and
20900 macros currently being executed are terminated (macro
21000 definitions are retained), all subjobs are put in line mode
21100 and all I/O currently inside the monitor is flushed. A new
21200 second segment is read in on top of the old one and its job
21300 count cleared to delete any subjobs which may have been
21400 initialized for message procedures when it was saved and the
21500 YES_@ flags are are all cleared. The trace flag is set to
21600 whatever its status was when the restart began. If the
21700 segment read in was written out after being used, it is up to
21800 the person who wrote it out to be sure its status is such
21900 that it can be used. In particular, there should be no
22000 messages existing in the segment. Finally, the trace file is
22100 release and the string 'INITIALIZED' is typed. The monitor
22200 then updates the run number and is ready for more commands.
22300 All subjobs logged in are in the state they were in
22400 previously, except they have been halted.
22500
22600 The file and device from which the second segment is read in
22700 is stored in the second segment. As assembled, it is
22800 SYS:GLBSEG. Segments which have been used and then written
22900 out should have stored in them the information as to were
23000 they were put for restarting the same segment (the
23100 information, in SIXBIT, goes in SETDEV and SETFIL which are
23200 internals in the second segment). You may override this
23300 information by giving any portion of it as arguments to the
23400 restart commands DEV: sets the device, FILE sets the file
23500 name, and DEV:FILE sets both. If neither are given and no
23600 name is available in the second segment, you will be asked
23700 for whatever is missing. After the new segment is read in,
23800 the device and file will be stored in it for future use. If
23900 there is an error for INIT, LOOKUP, or the core UUOs, a
24000 message will be typed and you will be asked for the device
24100 and file to try again. Core UUO errors are not usually
24200 recoverable, however, since the system may not have enough
24300 core available.
24400
24500 15. :DUMP
24600
24700 The command will dump the second segment onto the user's disk
24800 area. It will ask for a file name. It should only be used
24900 by experts. If any message procedures are pendind, or jobs
25000 are altering the global model, the dumped second segment will
25100 not be restartable.
25200
25300
25400 This repertoire will be expanded as more functions seem necessary.
25500 Please let me know of new features you desire.
25600
00100 5.0 Output.
00200
00300 All sorts of output will appear on your screen. In order to
00400 distinguish the output of several jobs, each string from a new source
00500 is prefaced by the logical name of that source and a "+". If a line
00600 of output comes from the same source as the last line, the logical
00700 name and "+" are omitted:
00800
00900 log+ This is from the first job.
01000 com+ This is from the compiler, and
01100 This is also from the compiler.
01200 mon+ This is from the monitor.
01300
01400 6.0 Run number
01500
01600 The global integer RUN contains the run number and should be
01700 used to name debugging files (as FOOnn.DBG). It will be incremented
01800 each time the monitor is loaded. It will be reset to one whenever
01900 the debugging files (*.DBG) on II,HE are deleted. The monitor will
02000 type
02100
02200 RUN nn
02300
02400 when it is started and is ready to go.
02500
02600 7.0 Trace output
02700
02800 The trace output, except for message procedures, is of the form
02900
03000 <source>→<dest.><TAB><text>
03100
03200 where <source> is where the text came from and <dest.> is where it is
03300 going, if not suppressed. The following special names may be used:
03400
03500 MON To or from monitor. If the sequence is <source>→MON→<dest.>
03600 ,as with RPG commands, MON will be omitted.
03700 TTY To or from the teletype.
03800 MACR A macro is being executed.
03900 DISK DISKIN is being executed.
04000
04100 8.0 COMMANDS FROM SUBJOBS
04200
04300 The monitor contains the message procedure MON_COM with
04400 accepts as its argument a string, called by value. The string will
04500 be put into the monitor's TTY input stream as though it had been
04600 typed by the user. It will be echoed on the TTY. This feature is
04700 provided mainly to allow subjobs to send commands to the monitor to
04800 login, run, and kill other subjobs, but may be used to send strings
04900 to other subjobs. Be warned, however, that if the string has a
05000 logical name prefixed to it, the monitor's default name will be
05100 changed at the point where the string appears in the input.
00100 9.0 Error messages
00200
00300 Below is a list of the error messages from the monitor.
00400 Unless noted, the last input from the TTY is in error and will be
00500 ignored. Except for the first message below, if an error message is
00600 generated while executing DISKIN, the DISKIN command will be
00700 terminated immediately with the message DISKIN TERMINATED.
00800
00900 ERROR MESSAGE CAUSE
01000
01100 TTY MODE CONFUSION
01200 The TTY is in character mode (currently means a monitor bug)
01300
01400 UNKNOWN DESTINATION-XXX
01500 Your last destination (XXX) is not logged in.
01600
01700 UNKNOWN COMMAND-XXX
01800 You gave the monitor a command (XXX) it did not recognize.
01900
02000 NO SUCH LOGICAL NAME-XXX
02100 A command specified a subjob not logged in. (subjob XXX)
02200
02300 ILLEGAL FOR MONITOR-XXX
02400 This command (XXX) cannot be applied to the monitor.
02500
02600 SPECIFY ONE DESTINATION-XXX
02700 This command (XXX) cannot be prefixed by ::
02800
02900 ALREADY LOGGED IN-XXX
03000 You are trying to log in a subjob using a logical name
03100 already logged in. (logical name is XXX)
03200
03300 MAXIMUM SUBJOB COUNT EXCEEDED
03400 You are trying to log in the 17th subjob.
03500
03600 NO PTY TODAY
03700 All system PTYs are in use. The login will be ignored
03800
03900 LOOKUP (ENTER) ON TRACE FILE FAILED
04000 UPDATE lost on the monitor trace file. You will lose if you
04100 do any more tracing.
04200
04300 MACRO LIMIT EXCEEDED
04400 You are trying to define your 21st macro. Shame!!
04500
04600 FILE NOT FOUND
04700 DISKIN could not find the requested file.
04800
04900 NOT ENOUGH PARAMETERS SUPPLIED
05000 The command needs more arguments (LOGIN,DISKIN, or DEFINE) or
05100 DISKINs file name has the wrong syntax.
05200
05300 CANNOT ENTER TRACE FILE
05400 Fatal initialization error. You lose if you turn on tracing.
05500
05600 REDEFINING MACRO xxxxx
05700 You are trying to define a macro which is all ready defined.
05800 This is a warning only, macro xxxxx will be redefined. This
05900 message does not terminate DISKIN.
06000
06100 RECURSIVE CALL ON DISKIN
06200 The file DISKIN is reading contains the DISKIN command, other
06300 than as a macro. This is bad form. It is also illegal.
06400
06500 JOB CAPACITY EXCEEDED - XXX
06600
06700 The system has no free job numbers for the job you are trying
06800 to log in (whose logical name is XXX).
06900
07000 LOGIN FAILED
07100 The system did not log in the subjob properly and put the PTY
07200 in monitor mode within five seconds. The attempted login has
07300 been flushed. If this happens constantly, there is a problem
07400 in the system. The output of the PTY during login will be
07500 type out just prior to this message.
07600
07700 HALT FAILED
07800 The system did not put the PTY in monitor mode withing five
07900 seconds. See last error message above.